Skip to content

Release v0.4.0 - Auto HTTP Handlers & OpenAPI Generation#95

Merged
RAprogramm merged 36 commits intomainfrom
dev
Jan 7, 2026
Merged

Release v0.4.0 - Auto HTTP Handlers & OpenAPI Generation#95
RAprogramm merged 36 commits intomainfrom
dev

Conversation

@RAprogramm
Copy link
Owner

@RAprogramm RAprogramm commented Jan 7, 2026

Summary

This release adds major new features for automatic HTTP handler generation and OpenAPI documentation.

New Features

Auto-Generated HTTP Handlers

  • api(handlers) attribute generates full CRUD endpoints
  • user_router() function provides ready-to-use Axum router
  • Selective handlers: handlers(get, list) for read-only APIs
  • Supports api(handlers(create, get, update, list)) for custom combinations

OpenAPI Documentation

  • UserApi struct with full OpenAPI spec generation
  • Configurable info: title, description, api_version
  • License: license, license_url
  • Contact: contact_name, contact_email, contact_url
  • Security schemes: cookie, bearer, api_key

Additional Features

  • Transactions: Multi-entity atomic operations with #[entity(transactions)]
  • API Versioning: deprecated and api_version attributes
  • EntityError: Derive macro for OpenAPI error documentation
  • Command Security: Per-command security configuration
  • Validation Constraints: Parse validator attributes for OpenAPI
  • Doc Comments: Extract /// comments for OpenAPI descriptions

Examples

All 10 examples now compile and work:

  • basic, filtering, relations, events, hooks
  • commands, transactions, soft-delete, streams, full-app

Version Bumps

  • entity-derive: 0.3.3 → 0.4.0
  • entity-core: 0.1.3 → 0.2.0
  • entity-derive-impl: 0.1.3 → 0.2.0

Breaking Changes

None - all existing code should continue to work.

Test Plan

  • All crates compile with cargo check --all
  • All tests pass with cargo test --all
  • Clippy passes with cargo clippy --all -- -D warnings
  • All 10 examples compile successfully
  • CI pipeline passes

RAprogramm and others added 27 commits January 7, 2026 08:48
Restructure examples to demonstrate each entity-derive feature:
- basic: renamed from axum-crud, simple CRUD operations
- filtering: #[filter], #[filter(like)], #[filter(range)]
- relations: #[belongs_to], #[has_many]
- events: #[entity(events)] with event enums
- hooks: #[entity(hooks)] with lifecycle hooks
- commands: #[entity(commands)], #[command] CQRS pattern
- transactions: #[entity(transactions)] atomic operations
- soft-delete: #[entity(soft_delete)] with restore
- streams: #[entity(streams)] async streaming
- full-app: complete e-commerce app with all features

All examples have publish = false to exclude from crates.io.
- Add workspace.exclude for examples directories
- Add postgres/api features to example crates
- Add async-trait and utoipa dependencies
- Add entity-core where needed
- Fix SPDX headers in migration files
- Fix type annotations for multi-entity repos
- Add utoipa::path attributes to basic example
- Update gitignore for example targets
- Add utoipa dependency to Cargo.toml
- Fix unused imports
- Add entity-core and utoipa dependencies
- Rename AccountCommandHandler to MyAccountHandler (avoid conflict with generated trait)
- Use source = "update" for UpdateEmail command
- Create separate input types for HTTP handlers (commands lack Deserialize)
- Use AccountRepository:: fully qualified syntax
- Simplified TransactionContext to use 'static lifetime for sqlx::Transaction
- Added extension traits for entity repository access (ctx.bank_accounts())
- Implemented pluralize() function for proper method naming
- Updated transactions example with fully qualified syntax
- Added cfg guards for postgres-specific code
- Added stream_filtered method to repository trait
- Added Filter type alias (same as Query struct)
- Implemented stream_filtered for PostgreSQL
- Fixed streams example with correct field names
- Added Serialize/Deserialize to AuditLog entity
- Added events feature for subscriber support
feat(examples): add comprehensive feature examples
- Add ApiConfig struct with tag, security, path_prefix, version options
- Parse api(...) nested attributes from #[entity(api(...))]
- Support public commands list for bypassing authentication
- Add has_api() and api_config() methods to EntityDef
- Comprehensive test coverage for all parsing scenarios
#76 feat: add api attribute parsing for OpenAPI integration
- Add api/ module with handlers, router, and openapi submodules
- Generate axum handlers with #[utoipa::path] annotations
- Support security configuration (bearer, api_key) per endpoint
- Mark public commands without authentication requirement
- Generate router factory function for easy integration
- Generate OpenApi struct for Swagger UI
- HTTP method selection based on command kind (POST/PUT/DELETE)
- Path parameters for commands requiring entity ID
- 4 unit tests for HTTP method selection
- Add utils/docs.rs module for doc comment extraction
- Extract /// comments from entity struct for tag descriptions
- Extract /// comments from fields for schema descriptions
- Use entity doc as fallback for tag_description in OpenAPI
- 6 unit tests for doc extraction functions
- Add utils/docs.rs module for doc comment extraction
- Extract /// comments from entity struct for tag descriptions
- Extract /// comments from fields for schema descriptions
- Use entity doc as fallback for tag_description in OpenAPI
- 6 unit tests for doc extraction functions
- Add validation.rs module for #[validate(...)] parsing
- Support length(min, max), range(min, max), email, url, regex
- Generate OpenAPI schema constraints (minLength, maxLength, etc.)
- Store raw attrs for passthrough to generated DTOs
- 8 unit tests for validation parsing
# Conflicts:
#	crates/entity-derive-impl/src/entity/parse/field.rs
- Add example.rs module for parsing #[example = ...] attributes
- Support string, integer, float, and boolean literals
- Support negative numbers
- Add ExampleValue enum with to_tokens() and to_schema_attr()
- Add example field to FieldDef with accessor methods
- Include 8 unit tests for parsing

Closes #80
- Add security field to CommandDef for per-command override
- Parse security = "..." option in #[command(...)] attributes
- Support "none" value to make specific commands public
- Update handler generation to use command security with priority:
  1. Command-level security override
  2. Entity-level public commands list
  3. Entity-level default security
- Add security_scheme_name helper for mapping schemes
- Add 3 unit tests for security parsing

Closes #81
- Create error.rs module with EntityError derive macro
- Parse #[status(code)] attributes for HTTP status codes
- Use doc comments as error descriptions
- Generate {Error}Responses struct with helper methods:
  - status_codes() - all error status codes
  - descriptions() - all error descriptions
  - utoipa_responses() - tuples for OpenAPI
- Add 4 unit tests for error parsing

Closes #82
- Wire up deprecated_in config to generate deprecated = true in utoipa
- Version is already supported via full_path_prefix()
- Add 5 unit tests for security scheme name mapping

Closes #83
* feat(api): add CRUD handler generation

Add `api(handlers)` option to generate REST handlers automatically:
- create_{entity} - POST handler
- get_{entity} - GET by ID handler
- update_{entity} - PATCH handler
- delete_{entity} - DELETE handler
- list_{entity} - GET list handler

Also adds separate routers:
- {entity}_router<R>() for CRUD (Repository trait)
- {entity}_commands_router<H>() for commands (CommandHandler trait)

Part of #67: fix examples with generated handlers

* #67 feat(api): add OpenAPI info config and selective handlers

- Add OpenAPI info configuration (title, description, version, license, contact)
- Add selective handlers via handlers(create, get, list) syntax
- Generate ErrorResponse and PaginationQuery schemas in OpenAPI
- Refactor path generation to only include enabled handlers
- Update router and crud modules to respect HandlerConfig
- Fix utoipa 5.x compatibility with Modify trait pattern

* #67 fix(openapi): register only schemas for enabled handlers

- OpenAPI now only includes CreateRequest if handlers.create is enabled
- OpenAPI now only includes UpdateRequest if handlers.update is enabled
- Response schema is always included (used by all read operations)
- Added 3 tests for selective handlers schema registration

* #67 fix(ci): show green status for non-dependabot PRs

Changed workflow to run for all PRs but skip auto-merge steps
for non-dependabot PRs. This shows green (success) instead of
gray (skipped) status in the PR checks.
- Bump entity-core: 0.1.3 -> 0.2.0
- Bump entity-derive: 0.3.3 -> 0.4.0
- Bump entity-derive-impl: 0.1.3 -> 0.2.0
- Bump workspace: 0.3.0 -> 0.4.0

Full-app example fixes:
- Add masterror dependency
- Add streams feature to entity-core
- Fix relation patterns (use #[has_many] at struct level)
- Add Serialize/Deserialize derives to AuditLog
- Simplify to single entity with api(handlers)
@RAprogramm RAprogramm changed the title Dev Release v0.4.0 - Auto HTTP Handlers & OpenAPI Generation Jan 7, 2026
Split 5 large modules (600-900 lines) into focused submodules:

- openapi.rs (922 lines) → openapi/ (6 files)
- crud.rs (708 lines) → crud/ (8 files)
- command.rs (630 lines) → command/ (4 files)
- api.rs (576 lines) → parse/api/ (4 files)
- entity.rs (806 lines) → parse/entity/ (8 files)

Changes:
- Replace inline comments with doc comments (//! and ///)
- Remove regular comments (allowed only in examples)
- Add detailed module-level documentation
- Improve code organization for better testability
Add tokio-level documentation to all parse/ and api/ submodules:

- crud/: delete, get, list, update handler generators
- openapi/: info, paths, schemas, security modules
- parse/api/: config, parser modules
- parse/command/: types, parser modules
- parse/entity/: def, accessors, constructor, helpers, projection

Each module now includes:
- Architecture diagrams showing data flow
- Type hierarchy tables
- Usage examples
- Function reference tables
@RAprogramm RAprogramm merged commit bc2df74 into main Jan 7, 2026
14 checks passed
@RAprogramm RAprogramm deleted the dev branch January 7, 2026 09:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant